Add JSDoc standard comments to all core utility functions and hooks

[AlAfiz]

Description

TypeScript provides type safety, but it doesn't explain intent. Complex math functions (like yield calculation) or custom React hooks need inline documentation for IDE autocomplete to be useful.

Acceptance Criteria

• Audit the lib/utils/ and hooks/ directories.
• Add a JSDoc block /** ... */ above every exported function.
• Include a plain-English description of what the function does.
• Document all @param inputs and the expected @returns output.
• If a function throws specific errors (e.g., "Insufficient Balance"), document them with @throws.

Technical Details

• Configure ESLint (eslint-plugin-jsdoc) to enforce JSDoc comments on newly created utility functions going forward.