Expand inline documentation for smart contracts

[YuManyl]

The contracts are well organized. Adding more inline comments explaining core logic and assumptions could make them easier to understand for contributors.
This would be especially helpful for developers reviewing or integrating with the contracts