Write an integration guide for the record-settle metering lifecycle

[mikewheeleer]

Document the end-to-end metering and settlement lifecycle

Description

The README in README.md does not explain how an integrator wires up the escrow: how to init, register and price a service, enable the allowlist, call record_usage, then compute_billing and settle. The full lifecycle in contracts/escrow/src/lib.rs is only discoverable by reading the source. This issue writes a practical, copy-pasteable integration guide.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add docs/escrow/integration.md walking through: deploy → init(admin) → register_service + set_service_price + set_service_metadata → optional allowlist/strict-registration → record_usage loop → compute_billing → settle.
• Include a sequence diagram and the role of each off-chain actor (agent, service owner, settlement loop).
• Show the relevant EscrowClient calls mirroring the patterns in contracts/escrow/src/test.rs.
• Cross-reference the events emitted at each step so integrators know what to index.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/contracts-27-integration-guide
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — only /// clarifications if needed.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — optionally add an end-to-end lifecycle test that the guide references.
  • Add documentation: add docs/escrow/integration.md; link from README.md.
  • Include NatSpec-style doc comments (///) where gaps are found.
  • Validate security: guide highlights pause, auth, and strict-mode considerations.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: the guide's example flow compiles as a test if one is added.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

docs: add end-to-end record-settle integration guide

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.