Add a developer guide and lifecycle diagram for the InvestmentStatus state machine in investment.rs

[Baskarayelu]

📋 Description

quicklendx-contracts/src/investment.rs defines InvestmentStatus::{Active, Withdrawn, Completed, Defaulted, Refunded} with a validate_transition enforcing that Active is the only non-terminal state (terminals cannot transition again). This state machine is the backbone of investor position tracking, but there is no developer doc explaining the legal transitions, which protocol action drives each, or how it stays in lockstep with invoice and escrow status.

Why this matters: investment status is what an investor's portfolio is built on, and it is tightly coupled to invoice/escrow transitions. Without a clear state-machine doc, integrators misread a Refunded vs Defaulted position and contributors risk adding an illegal transition. An authoritative diagram + guide makes the coupling explicit and the invariant teachable.

🎯 Requirements & Context

Functional requirements

• Create quicklendx-contracts/docs/investment-lifecycle.md documenting every InvestmentStatus and the legal transitions enforced by validate_transition.
• For each transition, name the driving entrypoint (accept_bid_and_fund -> Active; settlement -> Completed; refund_escrow_funds -> Refunded; default handling -> Defaulted; withdrawal -> Withdrawn).
• Document the coupling: which invoice/escrow status each investment status corresponds to.
• Include a Mermaid (or ASCII) state diagram.

Context & constraints

• Documentation only; optionally add /// doc comments on validate_transition and the status enum.
• Keep variant names and transition rules verbatim from the source.
• Soroban SDK 25.1.1.

🛠️ Suggested Execution

1. Fork & branch

git checkout -b docs/investment-lifecycle

2. Implement changes

• Trace the real transition sites in investment.rs/escrow.rs/settlement.rs/defaults.rs; write the doc and diagram.

3. Test & commit

cargo build -p quicklendx-contracts
cargo clippy -p quicklendx-contracts

• Verify the documented transitions match validate_transition and the entrypoint mapping is accurate.

Example commit message

docs(investment): add InvestmentStatus lifecycle guide with transition diagram

Documents legal transitions, driving entrypoints, and coupling to invoice/escrow status.

✅ Acceptance Criteria & Guidelines

Requirement	Target
All statuses + legal transitions documented	Required
Driving entrypoint per transition	Required
Coupling to invoice/escrow documented	Required
Diagram included; names verbatim	Required
cargo clippy clean (if doc comments added)	Required
Timeframe	96 hours from assignment

💬 Community & Support

Questions, design discussion, and help getting your environment running — join the QuickLendX contributor community on Discord: https://discord.gg/VpngvTjWa

Please drop a note in the channel when you pick this up so we can avoid duplicate work and unblock you fast. Clear communication during the PR keeps the review fast and friction-free. 🚀

[0xVida]

hi mainatainer i'd like to work on this issue, i will document the complete InvestmentStatus lifecycle including all legal transitions, their driving entrypoints and the relationship between investment, invoice and escrow states. I'll also include a clear state diagram and ensure the documentation accurately reflects the implementation in the codebase

[grantfox-oss]

🦊 GrantFox — @0xVida has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #1345)
2. Your PR will be reviewed by the QuickLendX maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@0xVida's PR #1385 was approved and merged by @Baskarayelu.

🏆 @0xVida: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (188 total points). Track your full progress on GrantFox.

👏 Great work, @0xVida! Keep contributing to QuickLendX.