Add JSDoc to shares helper module (closes #163)

[juanes96]

What this changes
Adds full JSDoc (@param, @returns, @throws, @example) to all exported members of the hand-written shares helper module (TOTAL_BASIS_POINTS, InvalidSharesError, validateShares, sharesFromWeights).

Why
The hand-written helpers lacked inline documentation, per #163.

Closes #163

[juanes96]

Heads up, the failing ci / contract check is unrelated to this change — it's a spell-check failure on README.md line 38 (unknown word "summarises"), pre-existing in main. This PR only touches sdk/src/shares.ts. Let me know if anything else is needed on my end.

[Spagero763]

contract fails on the docs spell-check: Unknown word (summarises) in README.md. That word's actually already allow-listed on main — your branch just predates it. Updating your branch to current main should clear this.