docs: diagram the three-phase billing deduct lifecycle

[samuelelijah585]

Overview

This PR documents the three-phase billing deduct lifecycle implemented in src/services/billing.ts (Phase 1 pending insert, Phase 2 Soroban deduct with retries, Phase 3 tx-hash persistence) so that client developers can implement correct retries and operators know which rows reconciliation must repair. It adds a row-state table, a sequence diagram, a per-flag meaning matrix, per-status retry guidance, and an explicit statement of the single-process semaphore limitation, and links the new section from the billing docs index.

Related Issue

Changes

📄 Billing lifecycle documentation

• [MODIFY] docs/billing-idempotency.md

  • Adds a row-state table covering pending, applied, and failed states, including which phase writes each state and which fields (alreadyProcessed, deductionApplied, reconciliationRequired) are expected in each.
  • Adds a sequence diagram (Mermaid) tracing a deduct request through Phase 1 → Phase 2 (with retry loop) → Phase 3, including the reconciliation-required branch.
  • Adds a flag-combination matrix giving a documented meaning for every combination of alreadyProcessed, deductionApplied, and reconciliationRequired.
  • States the single-process semaphore limitation: the per-user semaphore is in-process only, so concurrent requests across multiple instances are not mutually excluded and rely on the idempotency/reconciliation path.

• [MODIFY] docs/sdk/billing-deduct.md

  • Adds recommended client retry behaviour per HTTP status code (which statuses are safe to retry, which require backoff, and which must be surfaced to the caller or routed to reconciliation).
  • Cross-references the flag matrix so clients can branch on response flags rather than status alone.

• [MODIFY] docs/billing-index.md

  • Links the new lifecycle section so it is discoverable from the docs index.

Verification Results

Docs-only change; no test files were modified.
Reviewed documented states against the scenarios exercised by:
npm test -- src/services/billing.test.ts

Acceptance Criteria	Status
Each combination of response flags has a documented meaning	✅ Flag matrix in docs/billing-idempotency.md
Recommended client retry behaviour is listed per status code	✅ Retry table in docs/sdk/billing-deduct.md
The single-process semaphore limitation is stated	✅ Stated in docs/billing-idempotency.md
docs/billing-index.md links the section	✅ Index entry added

Closes #1331

[drips-wave]

@samuelelijah585 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits