docs/fix: align API error codes, event schemas, oracle execution flow, and liquidation specs with implementation (#660, #662, #663, #664, #666, #667, #655, #656, #657)

[ghzhost]

Summary of Changes

This PR addresses and resolves multiple documentation and specification inconsistencies with the actual Soroban smart contract implementation in SO4-Markets/contracts:

1. Exchange Router API & Error Codes (docs/exchange-router-api.md's Error Codes table lists only 3 of exchange_router's 7 error variants, omitting Paused entirely #660, docs/exchange-router-api.md's claim_funding_fees section names the wrong event topic (fee_clm instead of fnd_clm) #662, docs/exchange-router-api.md's create_order/create_deposit/create_withdrawal event payloads are stale — all three were enriched by #442 but the doc still shows the pre-enrichment 3-field shape #663, docs/exchange-router-api.md's Overview claims create_order is exposed as a direct single-action helper — it's actually the prime example of one that isn't #664):

   • Updated docs/exchange-router-api.md event payloads for create_order, create_deposit, and create_withdrawal to match the enriched schemas introduced in implementation (docs/exchange-router-api.md's create_order/create_deposit/create_withdrawal event payloads are stale — all three were enriched by #442 but the doc still shows the pre-enrichment 3-field shape #663).
   • Fixed outdated error codes in documentation to reflect current enum variants and mappings (docs/exchange-router-api.md's Error Codes table lists only 3 of exchange_router's 7 error variants, omitting Paused entirely #660, docs/exchange-router-api.md's claim_funding_fees section names the wrong event topic (fee_clm instead of fnd_clm) #662, docs/exchange-router-api.md's Overview claims create_order is exposed as a direct single-action helper — it's actually the prime example of one that isn't #664).

2. Oracle Execution Flow & Script Specs (docs/oracle.md claims submit_prices.sh signs a bundle and calls set_prices — it actually calls the unsigned set_prices_simple test path #666, docs/oracle.md's Price Pair (Min/Max) table describes increase/decrease execution price selection that doesn't match get_execution_price — it uses mid_price + impact, never min/max #667):

   • Corrected docs/oracle.md description of price execution logic: reflects mid_price + impact calculations rather than outdated min/max claims (docs/oracle.md's Price Pair (Min/Max) table describes increase/decrease execution price selection that doesn't match get_execution_price — it uses mid_price + impact, never min/max #667).
   • Fixed description of submit_prices.sh test execution path vs signed bundles (docs/oracle.md claims submit_prices.sh signs a bundle and calls set_prices — it actually calls the unsigned set_prices_simple test path #666).

3. Liquidation Flow & Position Utils (is_liquidatable's own comments contradict each other on whether PnL enters the primary comparison, and docs/liquidation-flow.md still describes the pre-#406-fix behavior #655, docs/liquidation-flow.md contradicts itself: §3 says the percentage fee split isn't implemented, but §4's worked example and §5's comparison table both use it as if it were live #656, docs/keeper-execution-flow.md calls oracle's price-submission function set_primary_price, which doesn't exist — the real entrypoint is set_prices #657):

   • Reconciled docs/liquidation-flow.md and comments in libs/position_utils/src/lib.rs regarding PnL inclusion in primary health factor checks.
   • Cleared contradictory comments and brought the liquidation documentation up to date with post-position_utils: is_liquidatable ignores unrealized PnL, hiding insolvent positions from liquidation #406 fixes.

Closes #660, closes #662, closes #663, closes #664, closes #666, closes #667, closes #655, closes #656, closes #657.