Document the escrow contract lifecycle, grace period, and violation threshold in contracts/README.md

[1nonlypiece]

📌 Description

The Soroban escrow crate (contracts/escrow/src/lib.rs) has grown well beyond
the basic lifecycle: it now includes transfer_ownership, a configurable
penalty-free GracePeriodSeconds, a ViolationThreshold that auto-freezes
funded commitments (EscrowStatus::Violated), default per-risk-profile
penalties, yield-pool accounting, and settle_commitment. TODO.md shows the
transfer_ownership documentation step is still unchecked, and contracts/README.md
does not reflect these capabilities.

This issue documents the full escrow lifecycle and configuration surface.

Goal: contracts/README.md accurately describes every entrypoint, state
transition, and configurable parameter so integrators and auditors can follow
the escrow behavior.

🎯 Requirements and Context

• Document the lifecycle: create_commitment → fund_escrow →
  {release/settle_commitment | refund/early_exit_commitment | dispute → resolve_dispute}, plus transfer_ownership (funded-only,
  owner-auth) and the Violated auto-freeze path.
• Document configuration: GracePeriodSeconds, ViolationThreshold, default
  penalties per RiskProfile, MAX_AMOUNT, MAX_DURATION_DAYS,
  MAX_PENALTY_BPS, and yield-pool funding.
• Document the stable error codes (Error enum 1–11) and how the backend's
  normalizeContractError consumes them.
• Include a worked refund/grace-period example consistent with the test suite.

🛠️ Suggested Execution

1. Create a branch

git checkout -b feature/escrow-contract-docs

2. Implement changes

• Rewrite/extend contracts/README.md with the lifecycle, config, and error
  tables above; cross-link contracts/escrow/src/lib.rs and test.rs.
• Check off the documentation step in TODO.md.

3. Test and commit

• Verify each documented entrypoint/error matches lib.rs signatures and the
  Error enum; confirm example numbers against test.rs.

Example commit message

docs: full escrow lifecycle, grace period, and violation threshold reference

✅ Guidelines

• Minimum 95% test coverage is N/A for docs, but every documented entrypoint
  and error code must match the contract exactly.
• Clear, auditor-friendly tables and a worked example.
• Timeframe: 96 hours.

🏷️ Labels

type-documentation · area-contracts · MAYBE REWARDED · GRANTFOX OSS · OFFICIAL CAMPAIGN

💬 Community & Support

• Join the CommitLabs contributor Discord: https://discord.gg/WV7tdYkJk
• Introduce yourself before starting to avoid duplicate work.
• Maintainers triage actively and review fast.

[Errordog2]

/attempt #614

Submitted a docs PR covering the escrow lifecycle/configuration reference requested here: #614

Validation:

• Cross-checked the documented public entrypoints and stable Error enum codes 1-11 against contracts/escrow/src/lib.rs.
• Cross-checked the grace-period refund example against the contract tests.
• Confirmed TODO.md now marks the contracts/README.md documentation item complete.

No public payment details included.