Generate docstrings that describe what the code actually does, not what its name implies

Write documentation for the getUserTier function in lib/billing/tier.ts in TSDoc, matching the /** */ block style already used elsewhere in lib/billing/ format. Before writing
anything, read the actual function body — every branch, every early return, every thrown error —
and check whether its name and any existing comment already describe that behavior accurately,
because a docstring generated from the name and surrounding comments alone just restates whatever
those already claim, right or wrong, and a wrong claim documented confidently is worse than no
documentation at all.

AUDIENCE
Other engineers on this team calling this function from a new feature, not external API consumers.

KNOWN NON-OBVIOUS BEHAVIOR TO MAKE SURE IS SURFACED
getUserTier returns 'free' for a user with a cancelled subscription still inside its paid billing period, not 'paid' — this surprises people.

FOR EACH FUNCTION OR EXPORT, DOCUMENT
1. What it actually does, in one sentence, checked against the real logic — not the name. If the
   name suggests something the code does not actually do, say so as a separate note rather than
   writing around the discrepancy silently.
2. Every parameter, with its real constraint as enforced by the code, not just its type — if a
   parameter's type allows a value the function will actually throw on or silently misbehave for,
   document that constraint explicitly rather than letting the type signature imply it is always
   safe to pass.
3. What it returns in every branch, not just the main one — including what happens on an empty
   result, an error path, or an early return, since a docstring that only describes the success
   path is describing a fraction of the function's real contract.
4. Any side effect beyond the return value — a mutation of an argument, a write to storage, a
   network call, a thrown exception — stated explicitly, since a caller reading only the return
   type has no way to know about a side effect the code performs but the signature does not
   surface.

CONSTRAINTS
- Do not describe an implementation detail that could change without changing the contract, such
  as which specific loop construct is used internally, as if it were part of the guaranteed
  behavior — document what callers can rely on, not how today's version happens to achieve it.
- If getUserTier returns 'free' for a user with a cancelled subscription still inside its paid billing period, not 'paid' — this surprises people. names something the current code does not actually do, or does differently
  than described, flag the mismatch explicitly rather than writing the docstring to match the
  gotcha note over the real code — the note might itself be stale.
- Match TSDoc, matching the /** */ block style already used elsewhere in lib/billing/ exactly, including whether examples are expected inline — a generated block
  that is close to the right format but not quite in the project's actual convention creates
  visible inconsistency across a codebase where every other function follows the real convention.