docs(investment): add InvestmentStatus lifecycle guide, state transition diagram and code doc comments

[0xVida]

Pull Request Template

📝 Description

This PR documents the InvestmentStatus state machine (Active, Withdrawn, Completed, Defaulted, Refunded) and its transition invariants enforced by validate_transition. It adds a developer guide with a Mermaid lifecycle diagram and updates Rust doc comments on the enum/methods.

🎯 Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Performance improvement
• Security enhancement
• Other (please describe):

🔧 Changes Made

Files Modified

• quicklendx-contracts/src/types.rs: Added detailed /// doc comments to the InvestmentStatus enum and its variants.
• quicklendx-contracts/src/investment.rs: Enhanced doc comments on validate_transition to reference the new guide and detail arguments, return values, errors, and driving entrypoints.

New Files Added

• quicklendx-contracts/docs/investment-lifecycle.md: Developer guide for the InvestmentStatus state machine, containing description of states, allowed transition matrix, coupling matrix, and Mermaid diagram.

Key Changes

• Documented allowed transitions from Active to Completed, Defaulted, Refunded, and Withdrawn.
• Documented terminal state behavior and couplings to corresponding InvoiceStatus and escrow state.
• Visually represented the state machine using a Mermaid flowchart.

🧪 Testing

• Unit tests pass (Checked with cargo build for compile check)
• Integration tests pass
• Manual testing completed
• No breaking changes introduced
• Cross-platform compatibility verified
• Edge cases tested

Test Coverage

Validated changes compile cleanly with cargo build -p quicklendx-contracts. Existing test coverage in test_investment_terminal_states.rs and test_investment_transitions.rs already validates these transitions; this PR only documents them.

📋 Contract-Specific Checks

• Soroban contract builds successfully
• WASM compilation works
• Gas usage optimized
• Security considerations reviewed
• Events properly emitted
• Contract functions tested
• Error handling implemented
• Access control verified

Contract Testing Details

Verified that the contract builds successfully with the updated doc comments.

📋 Review Checklist

• Code follows project style guidelines
• Documentation updated if needed
• No sensitive data exposed
• Error handling implemented
• Edge cases considered
• Code is self-documenting
• No hardcoded values
• Proper logging implemented

🔍 Code Quality

• Clippy warnings addressed
• Code formatting follows rustfmt standards
• No unused imports or variables
• Functions are properly documented
• Complex logic is commented

🚀 Performance & Security

• Gas optimization reviewed
• No potential security vulnerabilities
• Input validation implemented
• Access controls properly configured
• No sensitive information in logs

📚 Documentation

• README updated if needed
• Code comments added for complex logic
• API documentation updated
• Changelog updated (if applicable)

🔗 Related Issues

Closes #1345

📋 Additional Notes

Documentation-only updates with inline comments for codebase clarity and an external guide.

🧪 How to Test

1. Run cargo build -p quicklendx-contracts to ensure compiler doc comment checks pass.
2. Read the new markdown document quicklendx-contracts/docs/investment-lifecycle.md and check the rendering of the Mermaid diagram.

📸 Screenshots (if applicable)

N/A

⚠️ Breaking Changes

None

🔄 Migration Steps (if applicable)

N/A

[Baskarayelu]

the InvestmentStatus lifecycle guide + state diagram + doc comments make that state machine much easier to reason about. merging 📚