Add comments to the agents.jl file

[Datseris]

The agents.jl file is now very complex. It has macros and other non trivial things like

const __AGENT_GENERATOR__ = Dict{Symbol, Expr}()

which I don't even remember why we put it there...

Yet the file has practically no comments to guide the reader.

We should add plenty of comments, that explain all non-trivial lines of code. Most lines of code are non-trivial. E.g., what does

    @capture(new_type, _{new_params__})

do? I would say almost everything relate to macros is non-trivial.

Unfortunately, @Tortar I think you are the only one that can solve this issue, so it would be fantastic if you took an hour at some point and added a PR with comments that clarify the source code.